飞书智能体支持 Slash Command

Slash Command 是一种允许用户在飞书聊天框中通过输入 / 快速触发机器人服务的交互方式。开发者可以通过 OpenAPI 为自己的机器人应用注册一组自定义指令，这些指令会以列表形式展示在用户输入 / 后弹出的指令面板中，从而实现更直观、便捷的能力发现与调用。

适用场景

Slash Command 适用于以下场景：

• 高频快捷操作：将应用中最常用、最核心的功能注册为指令，如 /todo 创建任务、/meeting 预定会议，用户无需离开聊天窗口即可完成操作。

• 信息查询与检索：提供快速的信息查询入口，如 /stock 查询股价、/weather 查询天气，简化信息获取流程。

• 复杂任务引导：作为复杂工作流的起点，例如 /approval 发起审批，触发后机器人可以发送卡片消息，引导用户完成后续的多步操作。

• 开发者与运维工具：为开发和运维人员提供便捷的命令行工具，如 /deploy 发布服务、/log 查看日志，将飞书客户端转变为一个轻量级的运维入口。

前提条件

在开始接入 Slash Command 之前，请确保你已完成以下准备工作：

• 飞书客户端版本要求：PC 端 7.70 及以上版本，移动端 7.71 及以上版本。

• 创建并发布应用：你需要在 飞书开放平台 创建一个企业自建应用或商店应用。

• 启用机器人能力：进入应用详情页，在“应用能力”下添加并启用“机器人”能力。应用需要发布后，机器人才能被用户搜索和使用。

• 获取 OpenAPI 调用凭证：了解如何获取和使用 tenant_access_token 或 user_access_token，详情参考获取访问凭证。 配置生效延迟：

由于客户端存在缓存策略，通过 OpenAPI 对 Slash Command 进行创建、更新或删除后，配置的变更将在客户端上有约 5 分钟的生效延迟。完成操作后，请耐心等待或尝试重启飞书客户端以查看最新效果。

快速开始

本章节将引导你快速完成对 Slash Command 的创建、查询、更新和删除操作。所有接口均使用统一的复数形式路径。

接口与权限

开发者需要通过调用以下四个 OpenAPI 来管理应用的 Slash Command。

在调用接口前，请确保你的应用已在“权限管理”页面申请并开通了上述权限。

请求示例

以下 curl 命令展示了如何完成一次完整的指令生命周期管理。请将 YOUR_TENANT_ACCESS_TOKEN 替换为你自己的访问凭证。icon_key可选列表参考 「Slash Command Icon Key 说明」章节。

1. 创建一条指令

指令数量上限：每个应用可创建的 Slash Command 存在数量上限（当前为 100 条）。

创建一个名为 /greet 的指令。

curl --location --request POST 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "command": "greet",
    "description": {
        "default_value": "发送一句问候",
        "i18n": {
            "en_us": "Send a greeting",
            "zh_cn": "发送一句问候"
        },
        "icon": {
          "icon_key": "skill_outlined"
        }
    }
}'

成功响应：

{
    "code": 0,
    "msg": "success",
    "data": {
        "command_id": "7374693847629398036"
    }
}

• 必填字段: command (指令名称，不含 /) 和 description (指令描述)。description 内部必须包含 default_value 作为兜底文案。

• 可选字段：icon（指令 icon key），icon_key 可选列表参考「Slash Command Icon Key 说明」章节。

• 记录command_id: 请务必记录成功响应中返回的 command_id，这是后续更新和删除该指令的唯一标识。

2. 查询指令列表

查询当前应用下的所有指令。

curl --location --request GET 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN'

成功响应：

{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "command_id": "7374693847629398036",
                "command": "greet",
                "description": {
                    "default_value": "发送一句问候",
                    "i18n": {
                        "en_us": "Send a greeting",
                        "zh_cn": "发送一句问候"
                    }
                },
               "icon": {
                   "icon_key": "skill_outlined"
                },
                "update_time": "1716963953"
            }
        ]
    }
}

3. 更新一条指令

使用 command_id 更新指定指令的描述和 icon。

curl --location --request PATCH 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands/7374693847629398036' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "description": {
        "default_value": "发送一句更加热情的问候",
        "i18n": {
            "en_us": "Send a more enthusiastic greeting",
            "zh_cn": "发送一句更加热情的问候"
        },
        "icon": {
          "icon_key": "skill_outlined"
        }
    }
}'

成功响应：

{
    "code": 0,
    "msg": "success",
    "data": {}
}

4. 删除一条指令

使用 command_id 删除指定指令。

curl --location --request DELETE 'https://open.feishu.cn/open-apis/application/v7/app_slash_commands/7374693847629398036' \
--header 'Authorization: Bearer YOUR_TENANT_ACCESS_TOKEN'

成功响应：

{
    "code": 0,
    "msg": "success",
    "data": {}
}

典型错误码

在调用过程中，你可能会遇到以下典型错误，可根据错误码和提示信息进行排查。

接入流程

一个完整的 Slash Command 接入与管理流程包含以下步骤：

第 1 步：应用创建与权限配置

1. 访问 飞书开放平台，创建一个新的企业自建应用，或选择一个已有的应用。

2. 在应用详情页的 应用能力 中，确保已添加并启用 机器人 能力。

3. 在 权限管理 页面，搜索并开通 application:app_slash_command:write 和 application:app_slash_command:read 权限。

4. 完成上述配置后，创建并发布一个新的应用版本，使权限和机器人能力生效。

第 2 步：获取 Access Token

调用 Slash Command 相关接口需要应用的访问凭证 (tenant_access_token)。请参考 自建应用获取 tenant_access_token，编写获取和刷新 Token 的逻辑。

第 3 步：注册指令 (Create)

调用 POST /open-apis/application/v7/app_slash_commands 接口，为你希望暴露给用户的每一个功能注册一条指令。

• 一次性注册：建议在你的服务启动或初始化阶段，将所有需要支持的指令一次性批量注册。

• 记录 ID：将成功创建后返回的 command_id 与你的业务逻辑（例如功能模块、函数名）进行映射，并持久化存储，以便后续更新或删除。

第 4 步：客户端生效与查询 (List)

1. 等待生效：指令注册成功后，由于客户端缓存机制，需要等待约 5 分钟才能在聊天输入框中看到。你可以尝试重启飞书客户端来加速缓存刷新。

2. 验证：在与你的机器人单聊的对话框中，输入 /，查看弹出的指令面板中是否包含你刚刚注册的指令。

3. 程序查询：随时可以调用 GET /open-apis/application/v7/app_slash_commands 接口，从服务端视角查询当前应用已成功注册的所有指令列表，从而核对或同步你的本地指令状态。 客户端缓存与延迟的影响：

客户端为了提升性能，会对应用的 Slash Command 列表进行缓存，缓存有效期约为 3 分钟。这意味着：

• 创建/更新：新的指令或对现有指令的修改，最长可能需要 注册延迟(5分钟) + 缓存刷新(3分钟) 才能在所有用户端可见。

• 删除：已删除的指令，可能在用户的指令面板中继续“残留”最多 3 分钟，直到下一次缓存过期并重新拉取。

因此，在进行管理操作后，请给予系统足够的同步时间。

第 5 步：更新与删除 (Update & Delete)

• 更新：当你需要修改某个指令的描述（例如，文案优化、功能变更说明）时，使用创建时保存的 command_id 调用 PATCH /open-apis/application/v7/app_slash_commands/:command_id 接口。

• 删除：当某个功能下线或不再希望通过 Slash Command 暴露时，使用对应的 command_id 调用 DELETE /open-apis/application/v7/app_slash_commands/:command_id 接口。

第 6 步：回滚与清理

• 回滚：如果一次发布后希望撤销某条指令，本质上就是删除操作。

• 重建：指令的 command 名称在被删除后即可再次使用。如果你误删了一条指令，可以立即使用相同的 command 和 description 重新调用创建接口。服务端会生成一个全新的 command_id，实现“原地重建”。

• 全量清理：在下线整个应用或重构指令体系时，你可以先通过 GET 接口拉取所有指令的 command_id，然后遍历列表，逐一调用 DELETE 接口，完成所有指令的清理工作。

最佳实践

遵循以下实践，可以帮助你更稳定、高效地使用 Slash Command OpenAPI。

命名规范

• 使用业务前缀：为了避免不同应用或应用内不同模块之间的指令冲突，建议为 command 名称添加有意义的前缀。例如，如果你的应用名为 “订单助手”，可以命名为 order_create、order_query。

• 动词优先：采用 动词-名词 的格式，如 create-task、search-file，使指令意图更加清晰。

• 简洁明了：指令名称应简短易记，避免使用过长或复杂的单词。

并发与幂等

• 创建操作的幂等性：POST 创建接口本身不是幂等的，但服务端对 command 名称做了唯一性约束。如果短时间内使用相同的 *command 名称发起多次创建请求，只有第一次会成功（返回 code: 0），后续请求将失败并返回 code: 40000000 及 msg: "command already exists"*。因此，调用方无需在客户端实现复杂的创建防重逻辑，只需判断响应码即可。

• 更新/删除操作的幂等性：PATCH 和 DELETE 操作在设计上是幂等的。对同一个 command_id 多次执行相同的更新，结果保持一致；对一个已删除的 command_id 多次调用删除，后续请求会返回 command_id not found，但从系统状态来看，结果同样是一致的（指令不存在）。

错误处理

在编写代码时，建议对以下几类关键错误进行捕获和处理：

• 指令已存在 (command already exists)：当创建指令时收到此错误，表明该指令名已被占用。此时应放弃创建，并可根据业务需要调用 GET 接口获取现有指令的 command_id，转为更新逻辑。

• 指令 ID 未找到 (command_id not found)：当更新或删除时收到此错误，表明目标指令已被删除或从未存在。此时应停止操作，并检查传入的 command_id 是否正确，或同步本地的指令状态。

• 鉴权错误 (99991661 / 99991663)：收到这类错误时，应检查 Authorization 请求头和 access_token 的有效性，并触发 Token 刷新机制。

• 参数校验错误 (99992402 / 9499)：这类错误通常由开发阶段的编码疏漏导致。应根据错误提示检查请求体的字段和结构，确保符合 API 定义。

数量与版本管理

• 指令数量上限：每个应用可创建的 Slash Command 存在数量上限（当前为 100 条）。
• 批量操作建议：当需要大规模清理指令时，建议的流程是：

1. 调用 GET 接口拉取当前全量指令列表。

2. 在本地计算出需要删除的指令 command_id 集合。

3. 遍历该集合，逐一调用 DELETE 接口完成删除。

Header 要求

• Content-Type: application/json; charset=utf-8：对于 POST 和 PATCH 请求，这是必须的。

• Authorization: Bearer <token>：所有请求必须携带。

Slash Command Icon Key 说明

本章列举用于 Slash Command 的创建和更新时icon_key参数的可选列表，默认为skill_outlined。

icon_key	图标
skill_outlined
light-ai_outlined
chat-ai_outlined
ai-edit-continue_outlined
education-ai_outlined
ai-trans-switch_outlined
language-ai_outlined
toolbar-more-ai_outlined
image-ai_outlined
ai-agent_outlined
ai-deepthink_outlined
ai-style_outlined
ai-reminder_outlined
ai-block_outlined
ai-simplify-expression_outlined
promptword_outlined
meeting-ai_outlined
ai-improvewriting_outlined
slash-ai_outlined
pa-cost-ai_outlined
update-ai_outlined
diagnosis-ai_outlined
ai-functions_outlined
mic-ai_outlined
search-ai_outlined
explanation-ai_outlined
add-ai_outlined
add-chat-ai_outlined
ai-notification_outlined
dynamic-layout_outlined
ai-doc_outlined
home_outlined
mail_outlined
browser-mac_outlined
flag_outlined
calendar-line_outlined
sent_outlined
gift_outlined
tag_outlined
cloud_outlined
bonus-payroll_outlined
vote_outlined
chat_outlined
emoji_outlined
member_outlined
robot_outlined
mic_outlined
raisehand_outlined
officephone_outlined
effects_outlined
labs_outlined
computer_outlined
clear_outlined
mouse_outlined
cellphone_outlined
cursor_outlined
plugin_outlined
edit_outlined
style-fillcolor_outlined
codeblock_outlined
code_outlined
folder_outlined
file-link-word_outlined
file-link-sheet_outlined
file-link-image_outlined
global-link_outlined
champion_outlined
local_outlined
day_outlined
waiting_outlined
database_outlined
marketplace_outlined

FAQ

Q1：为什么我调用接口时返回 404 Not Found？

A1：404 错误通常由以下原因导致：

1. URL 路径错误：请检查你的请求 URL 是否严格遵循文档格式 /open-apis/application/v7/app_slash_commands (对于列表和创建) 或 /open-apis/application/v7/app_slash_commands/:command_id (对于更新和删除)。特别注意路径是复数形式 commands。

2. 环境不匹配：如果你在测试环境（如 BOE）进行调试，但请求发往了线上环境域名 (open.feishu.cn)，或者未正确携带 x-tt-env 头部，可能导致路由失败。

Q2：我的指令已经创建成功，为什么在飞书里输入 / 看不到？

A2：这通常是由于缓存和生效延迟导致的。

1. 服务端延迟：从接口调用成功到配置在所有数据中心同步完成，有分钟级的延迟。

2. 客户端缓存：飞书客户端会对指令列表进行缓存（约 3 分钟）。

3. 排查步骤：

• 耐心等待：在创建或更新后，至少等待 5 分钟。

• 重启客户端：完全退出飞书客户端再重新登录，可以强制刷新缓存。

• 调用 GET 接口确认：调用列表接口，检查你的指令是否已存在于服务端返回的列表中。如果存在，说明服务端已处理成功，问题在于客户端缓存。

Q3：调用接口返回 code: 99991640, msg: "lacks permission"，这是为什么？

A3：这个错误明确表示你的应用缺少调用该接口所需的权限。

1. 检查权限范围 (Scope)：请前往 飞书开放平台 > 你的应用 > “权限管理”页面。

2. 确认权限：确保 application:app_slash_command:write (用于写操作) 和 application:app_slash_command:read (用于读操作) 已被添加并处于“已开通”状态。

3. 重新发布版本：如果在应用已发布后才添加的权限，你需要创建一个新的应用版本并重新发布，权限才会正式生效。

Q4：为什么我的 description.i18n 国际化配置没有生效？

A4：i18n 字段的 key 必须是标准的语言代码，value 为对应语言的描述文本。

• 正确结构:

    "description": {
        "default_value": "默认描述",
        "i18n": {
            "zh_cn": "中文描述",
            "en_us": "English Description",
            "ja_jp": "日本語の説明"
        }
    }

• 错误结构:

    // 错误示例1：i18n 不是一个 map/object
    "i18n": "some string" 

// 错误示例2：语言代码不标准
    "i18n": {
        "chinese": "中文描述" 
    }

请确保 i18n 的值是一个严格的 map[string]string 结构，且 key 使用 zh_cn, en_us 等标准代号。

Q5：我可以为一个应用创建多少个 Slash Command？

A5：目前，单个应用最多可以创建 100 条 Slash Command。建议你精选应用的核心功能进行注册，保持指令列表的简洁和高效。如果指令过多，用户反而难以查找和使用。